# Migration

import ThemedImage from "@theme/ThemedImage";

Migrating existing Deployments running in Kubernetes is very simple using the `rig-ops migrate` command.

The tool is built to ensure that the migration is happening in-place and *without incurring any downtime*, even from existing toolchains that
is built upon Helm or similar.
Read more about this [here](/operator-manual/migration#applying-changes).

The tool works by scanning your targeted cluster for running deployments and finds all resources associated with them; Services, Ingresses, ConfigMaps, etc.

The command uses a mix of the Rig Platform and the in-cluster running Rig Operator to compute *dry run* versions of a Capsule, that in
turn is compared to the running resources. Using this feedback, it's trivial to adjust the `migrate` parameters and cluster configuration
to allow a seamless migration.

:::info Download `rig-ops` CLI
Go to [rig-ops](/operator-manual/cli) for instructions on how to install the `rig-ops` CLI, that contains the `migrate` command.
:::

## Selecting a deployment

First step is to select a deployment to migrate. When running `rig-ops migrate` without any arguments, the tool will query the Cluster and show the list of deployments that can be migrated:

<ThemedImage
  alt="Select Deployment"
  sources={{
    light: "/img/operator-manual/migrate-deployments.png",
    dark: "/img/operator-manual/migrate-deployments.png",
  }}
/>


After selecting a deployment, the tool will compute a *diff* between resources generated by a to-be Capsule and the existing Cluster resources.
The next step allows the user to navigate the changes and validate that the to-be capsule matches expectations.

<ThemedImage
  alt="Capsule breakdown"
  sources={{
    light: "/img/operator-manual/migrate-parts.png",
    dark: "/img/operator-manual/migrate-parts.png",
  }}
/>

The diff itself, is a full diff between how the resource looks now (if exists) and exactly how it will look after being applied. Since the
tool is using the Operator, it's possible to get Kubernetes to perform the rendering of the resource with all runtime-properties associated to it.

That means the output is 1:1 identical with what would happen if the change were to be applied.

<ThemedImage
  alt="Apply changes"
  sources={{
    light: "/img/operator-manual/migrate-diff.png",
    dark: "/img/operator-manual/migrate-diff.png",
  }}
/>

If satisfied, `Ctrl-C` will leave the view and exit the tool.


## Applying changes

By default, no changes are made when running the tool. It's only when `--apply` is given, that the tool will, and the end of existing instructions,
query if the tool should apply the changes against the Platform - that means creating the Capsule if it doesn't exist, and start a deployment with
the new configuration.

<ThemedImage
  alt="Apply changes"
  sources={{
    light: "/img/operator-manual/migrate-apply.png",
    dark: "/img/operator-manual/migrate-apply.png",
  }}
/>

When a Capsule migration is applied, the resources in the Kubernetes cluster are automatically overridden by Operator. That means that
objects that was previously managed by e.g. Helm resources, will now be managed by the Operator instead. Due to how Ownership References
are handled in Kubernetes, this also means Helm will abort if used instead and thus ensuring the two systems won't compete against each
other.

This also has another side-effect; the migration is happening seamless and will have no impact on uptime.

:::info Live migration
Live migration is a key feature in adopting the Rig Platform. It is however still advised to:

1. Carefully review the diffs in the `rig-ops migrate` tool
2. Try migrating in a non-production environment

before moving forward with the actual migration.
:::

## Offline execution

While the tooling is using the Operator to compute the diff, it's possible to generate a diff from offline resources as well. That means
a dump of one Kubernetes cluster can be used instead of querying it in a live settings.

A good example is the following flow:

1. Produce a dump of non-sensitive objects from a production environment:
    ```bash
    kubectl get deployment,service,horizontalpodautoscaler.autoscaling,ingress,cronjob.batch -A -o yaml > objects.yaml
    ```
2. With a non-production cluster (e.g. KinD running on the local machine), run the migration against the production objects:
    ```bash
    rig-ops migrate -f objects.yaml
    ```
3. Apply the changes to the local cluster and further explore the objects as Capsules through the Platform.
